<?php
/**
 * Interface for cacher classes
 *
 * Copyright (C) 2008  Sean Hickey
 * 
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 *
 * @author Sean Hickey <sean@headzoo.com>
 * @version $Id: Interface.php 387 2008-07-03 05:35:19Z sean $
 * @package Alinks_Cacher
 */
interface Alinks_Cacher_Interface
{
	/**
	 * Sets the caching options
	 *
	 * @param array $options The options
	 * @return Alinks_Cacher_File
	 */
	function setOptions(array $options);
	
	/**
	 * Returns the caching options
	 *
	 * @return array
	 */
	function getOptions();
	
	/**
	 * Returns if cached content exists for the given key
	 *
	 * @param string $key The cache key
	 * @param string $namespace The cache namespace
	 * @return bool
	 */
	function exists($key, $namespace);
	
	/**
	 * Sets content to be cached
	 *
	 * @param string $key The cache key
	 * @param string $namespace The cache namespace
	 * @param mixed $value The cache value
	 * @param int $expires Number of seconds to keep the value cached
	 * @return Alinks_Cacher_Interface
	 */
	function set($key, $namespace, $value, $expires = 0);
	
	/**
	 * Returns cached content
	 *
	 * Throws a Alinks_Cacher_Exception if no cache exists for the
	 * given key and namspace. Use exists() first to be sure the cached
	 * content exists.
	 *
	 * @param string $key The cache key
	 * @param string $namespace The cache namespace
	 * @return mixed
	 */
	function get($key, $namespace);
	
	/**
	 * Deletes any cached content for the given key and namespace
	 *
	 * Returns true if the cache was deleted, false if not. False doesn't
	 * mean an error. It could just mean there was no cache to delete.
	 *
	 * @param string $key The cache key
	 * @param string $namespace The cache namepsace
	 * @return bool
	 */
	function delete($key, $namespace);
	
	/**
	 * Flushes the cache
	 *
	 * Flushes the cache. If $namspace is specified, then only cached
	 * content within that namespace will be flushed.
	 *
	 * This method always returns true.
	 *
	 * @param string $namespace The cache namespace
	 * @return bool
	 */
	function flush($namespace = null);
}